<HTML>
<CENTER><A HREF = "http://sparta.sandia.gov">SPARTA WWW Site</A> - <A HREF = "Manual.html">SPARTA Documentation</A> - <A HREF = "Section_commands.html#comm">SPARTA Commands</A> 
</CENTER>






<HR>

<H3>create_particles command 
</H3>
<H3>create_particles/kk command 
</H3>
<P><B>Syntax:</B>
</P>
<PRE>create_particles mix-ID style args keyword value ... 
</PRE>
<UL><LI>mix-ID = ID of mixture to use when creating particles 

<LI>style = <I>n</I> or <I>single</I> 

<PRE>  <I>n</I> args = Np
    Np = 0 or number of particles to create
  <I>single</I> args = species-ID x y z vx vy vz
    species-ID = ID of species of single particle
    x,y,z = position of particle (distance units)
    vx,vy,vz = velocity of particle (velocity units) 
</PRE>
<LI>zero or more keyword/value pairs may be appended 

<LI>keyword = <I>global</I> or <I>region</I> or <I>species</I> or <I>density</I> or <I>temperature</I> or <I>velocity</I> or <I>twopass</I> 

<PRE>  <I>global</I> value = <I>yes</I> or <I>no</I>
  <I>region</I> value = region-ID
  <I>species</I> values = svar xvar yvar zvar
    svar = name of equal-style variable for species
    xvar,yvar,zvar = names of internal-style variables for x,y,z
  <I>density</I> values = dvar xvar yvar zvar
    svar = name of equal-style variable for density
    xvar,yvar,zvar = names of internal-style variables for x,y,z
  <I>temperature</I> values = tvar xvar yvar zvar
    svar = name of equal-style variable for temperature
    xvar,yvar,zvar = names of internal-style variables for x,y,z
  <I>velocity</I> values = vxvar vyvar vzvar xvar yvar zvar
    vxvar,vyvar,vzvar = names of equal-style variables for vx,vy,vz
    xvar,yvar,zvar = names of internal-style variables for x,y,z
  <I>twopass</I> values = none 
</PRE>

</UL>
<P><B>Examples:</B>
</P>
<PRE>create_particles background n 0
create_particles air n 100000 region sphere
create_particles air n 100000 global yes
create_particles air single 3 5.0 6.0 5.4 10.0 -1.0 0.0
create_particles air n 0 species mySpecies xpos NULL zpos
create_particles air n 0 density myDens xgrid ygrid NULL
create_particles air n 0 temperature myTemp xgrid ygrid zgrid
create_particles air n 0 velocity myVx NULL myVz xpos ypos NULL twopass 
</PRE>
<P><B>Description:</B>
</P>
<P>Create particles and add them to the simulation domain.  The
attributes of individual particles, such as species and velocity, are
determined by the mixture attributes, as specied by the <I>mix-ID</I>.  In
particular the <I>temp</I>, <I>trot</I>, <I>tvib</I>, and <I>vstream</I> attributes of the
mixture affect create particle velocities and internal energy modes.
See the <A HREF = "mixture.html">mixture</A> command for more details.  Note that
this command can be used multiple times to add more and more
particles.
</P>
<P>Particles are only created in grid cells which are entirely external
to surfaces.  Particles are not created in grid cells cut by surfaces.
</P>
<P>IMPORTANT NOTE: When a particle is created at a specified temperature
(as set by the <A HREF = "mixture.html">mixture</A> command), it's rotational and
vibrational energy will also be initialized, consistent with the
mixture temperatures.  The <I>rotate</I> and <I>vibrate</I> options of the
<A HREF = "collide_modify.html">collide_modify</A> command determine how internal
energy modes are initialized.  If the <A HREF = "collide.html">collide</A> command
has not yet been specified, then no rotational or vibrational energy
will be assigned to created particles.  Thus if you wish to create
particles with non-zero internal energy, the <A HREF = "collide.html">collide</A>
and (optionally) <A HREF = "collide_modify.html">collide_modify</A> commands must be
used before this command.
</P>
<P>If the <I>n</I> style is used with <I>Np</I> = 0, then the number of created
particles is calculated by SPARTA as a function of the global <I>fnum</I>
value, the mixture number density, and the flow volume of the
simulation domain.
</P>
<P>The <I>fnum</I> value is set by the <A HREF = "global.html">global fnum</A> command.  The
mixture <I>nrho</I> is set by the <A HREF = "mixture.html">mixture</A> command.  The flow
volume of the simulation is the total volume of the simulation domain
as specified by the <A HREF = "create_box.html">create_box</A> command, minus any
volume that is interior to surfaces defined by the
<A HREF = "read_surf.html">read_surf</A> command.  Note that the flow volume
includes volume contributions from grid cells cut by surfaces.
However particles are only created in grid cells entirely external to
surfaces.  This means that particles may be created in external cells
at a (slightly) higher density to compensate for no particles being
created in cut cells that still contribute to the overall flow volume.
</P>
<P>If the <I>n</I> style is used with a non-zero <I>Np</I>, then exactly <I>Np</I>
particles are created, which can be useful for debugging or
benchmarking purposes.
</P>
<P>Based on the value of <I>Np</I>, each grid cell will have a target number
of particles <I>M</I> to insert, which is a function of the cell's volume
as compared to the total system flow volume.  If <I>M</I> has a fractional
value, e.g. 12.5, then 12 particles will be inserted, and a 13th
depending on the outcome of a random number generation.  As grid cells
are looped over, the remainder fraction is accumulated, so that
exactly <I>Np</I> particles are created across all the processors.
</P>
<P>IMPORTANT NOTE: The preceeding calculation is actually done using
<I>weighted</I> cell volumes.  Grid cells can be weighted using the <A HREF = "global.html">global
weight</A> command.
</P>
<P>Each particle is inserted at a random location within the grid cell.
The particle species is chosen randomly in accord with the <I>frac</I>
settings of the collection of species in the mixture, as set by the
<A HREF = "mixture.html">mixture</A> command.  The velocity of the particle is set
to the sum of the streaming velocity of the mixture and a thermal
velocity sampled from the thermal temperature of the mixture.  Both
the streaming velocity and thermal temperature are also set by the
<A HREF = "mixture.html">mixture</A> command.  The internal rotational and
vibrational energies of the particle are also set based on the <I>trot</I>
and <I>tvib</I> settings for the mixture, as explained above.
</P>
<P>The <I>single</I> style creates a single particle.  This can be useful for
debugging purposes, e.g. to advect a single particle towards a
surface.  A single particle of the specified species is inserted at
the specified position and with the specified velocity.  In this case
the <I>mix-ID</I> is ignored.
</P>
<HR>

<P>This is the meaning of the other allowed keywords.
</P>
<P>The <I>global</I> keyword only applies when the <I>n</I> style is used, and
controls how particles are generated in parallel.
</P>
<P>If the value is <I>yes</I>, then every processor loops over all <I>Np</I>
particles.  As the coordinates of each is generated, each processor
checks what grid cell it is in, and only stores the particle if it
owns that grid cell.  Thus an identical set of particles are created,
no matter how many processors are running the simulation
</P>
<P>IMPORTANT NOTE: The <I>global</I> yes option is not yet implemented.
</P>
<P>If the value is <I>no</I>, then each of the <I>P</I> processors generates a
<I>N/P</I> subset of particles, using its own random number generation.  It
only adds particles to grid cells that it owns, as described above.
This is a faster way to generate a large number of particles, but
means that the individual attributes of particles will depend on the
number of processors and the mapping of grid cells to procesors.  The
overall set of created particles should have the same statistical
properties as with the <I>yes</I> setting.
</P>
<P>If the <I>region</I> keyword is used, then a particle will only added if
its position is within the specified <I>region-ID</I>.  This can be used to
only allow particle insertion within a subset of the simulation
domain.  Note that the <I>side</I> option for the <A HREF = "region.html">region</A>
command can be used to define whether the inside or outside of the
geometric region is considered to be "in" the region.
</P>
<P>IMPORTANT NOTE: If the <I>region</I> and <I>n</I> keywords are used together,
less than N particles may be added.  This is because grid cells will
be candidates for particle insertion, unless they are entirely outside
the bounding box that encloses the region.  Particles those grid cells
attempt to add are included in the count for N, even if some or all of
the particle insertions are rejected due to not being inside the
region.
</P>
<P>The <I>species</I> keyword can be used to create particles with a
spatially-dependent separation of species.  The specified <I>svar</I> is
the name of an <A HREF = "variable.html">equal-style variable</A> whose formula
should evaluate to a species number, i.e. an integer from 1 to Nsp,
where Nsp is the number of species in the mixture with mix-ID.  Since
equal-style variables evaluate to floating-point values, this value is
truncated to an integer value.  The formula for the species variable
can use one or two or three variables which will store the x, y, or z
coordinates of the particle that is being created.  If used, these
variables must be <A HREF = "variable.html">internal-style variables</A> defined in
the input script; their initial numeric values can be anything.  They
must be internal-style variables, because this command resets their
values directly.  Their names are specified as <I>xvar</I>, <I>yvar</I>, and
<I>zvar</I>.  If any of them is not used in the <I>svar</I> formula, it can be
specified as NULL.
</P>
<P>When a particle is added, its coordinates are stored in the <I>xvar</I>,
<I>yvar</I>, <I>zvar</I> variables if they are specified.  The <I>svar</I> variable
is then evaluated.  The returned value is used to set the species of
that particle, based on the list of species defined for the mixture.
If the returned value is <= 0 or greater than Nsp = the number of
species in the mixture, then no particle is created.
</P>
<P>As an example, these commands can be used in a 2d simulation, to
create a particle distribution with species 1 on top of species 2 with
a sinudoidal interface between the two species, as illustrated in the
snapshot of the initial particle distribution.  Click on the image for
a larger version.  Note that when using this option less than the
requested N particles can be created if the species variable returns
values <= 0 or greater than Nsp = the number of species in the
mixture.
</P>
<PRE>variable x internal 0
variable y internal 0
variable n equal 3
variable s equal "(v_y < 0.5*(ylo+yhi) + 0.15*yhi*sin(2*PI*v_n*v_x/xhi)) + 1"
create_particles species n 10000 species s x y NULL 
</PRE>
<CENTER><A HREF = "JPG/species_variation.jpg"><IMG SRC = "JPG/species_variation_small.jpg"></A>
</CENTER>
<P>The <I>density</I> keyword can be used to create particles with a
spatially-dependent density variation.  The specified <I>dvar</I> is the
name of an <A HREF = "variable.html">equal-style variable</A> whose formula should
evaluate to a positive value.  The formula for <I>dvar</I> can use one or
two or three variables which will store the x, y, or z coordinates of
the geometric center point of a grid cell.  If used, these other
variables must be <A HREF = "variable.html">internal-style variables</A> defined in
the input script; their initial numeric values can by anything.  Their
names are specified as <I>xvar</I>, <I>yvar</I>, and <I>zvar</I>.  If any of them is
not used in the <I>dvar</I> formula, it can be specified as NULL.
</P>
<P>When particles are added to a grid cell, its center point coordinates
are stored in <I>xvar</I>, <I>yvar</I>, <I>zvar</I> if they are defined.  The <I>dvar</I>
variable is then evaluated.  The returned value is used as a scale
factor on the number of particles to create in that grid cell.  Thus a
value of 0.5 would create half as many particles in that grid cell as
would otherwise be the case, due to the global <I>fnum</I> and mixture
<I>nrho</I> settings that define the density, as explained above.  A value
of 1.2 would create 20% more particles in that grid cell.
</P>
<P>As an example, these commands can be used in a 2d simulation, to
create more particles towards the upper right corner of the domain and
less towards the lower left corner, as illustrated in the snapshot of
the initial particle distribution.  Click on the image for a larger
version.  Note that less than requested N particles will be created in
this case because all the scale factors generated by the variable <I>d</I>
are less than 1.0.
</P>
<PRE>variable x internal 0
variable y internal 0
variable d equal "v_x/xhi * v_y/yhi"
create_particles air n 10000 density d x y NULL 
</PRE>
<CENTER><A HREF = "JPG/density_variation.jpg"><IMG SRC = "JPG/density_variation_small.jpg"></A>
</CENTER>
<P>The <I>temperature</I> keyword can be used to create particles with a
spatially-dependent thermal temperature variation.  The specified
<I>tvar</I> is the name of an <A HREF = "variable.html">equal-style variable</A> whose
formula should evaluate to a positive value.  The formula for the
<I>tvar</I> variable can use one or two or three variables which will store
the x, y, or z coordinates of the geometric center point of a grid
cell.  If used, these other variables must be <A HREF = "variable.html">internal-style
variables</A> defined in the input script; their initial
numeric values can by anything.  Their names are specified as <I>xvar</I>,
<I>yvar</I>, and <I>zvar</I>.  If any of them is not used in the <I>tvar</I> formula,
it can be specified as NULL.
</P>
<P>When particles are added to a grid cell, its center point coordinates
are stored in <I>xvar</I>, <I>yvar</I>, <I>zvar</I> if they are defined.  The <I>tvar</I>
variable is then evaluated.  The returned value is used as a scale
factor on the thermal temperature number for particles created in that
grid cell.  Thus a value of 0.5 would create particles with a thermal
temperature half of what would otherwise be the case, due to the
mixture <I>temp</I> setting which defines the thermal temperature, as
explained above.  A value of 1.2 would create particles with a 20%
higher thermal temperature.
</P>
<P>As an example, these commands can be used in a 2d simulation, to
create a thermal temperature gradient in x, where the temperature on
the left side of the box is the default value, and the temperature on
the right side is 3x larger.
</P>
<PRE>variable x internal 0
variable t equal "1.0 + 2.0*(v_x-xlo)/(xhi-xlo)"
create_particles air n 10000 temperature t x NULL NULL 
</PRE>
<P>The <I>velocity</I> keyword can be used to create particles with a
spatially-dependent streaming velocity.  The specified <I>vxvar</I>,
<I>vyvar</I>, <I>vzvar</I> are the names of <A HREF = "variable.html">equal-style
variables</A> whose formulas should evaluate to the
corresponding component of the streaming velocity.  If any of them are
specified as NULL, then that streaming velocity component is set by
the corresponding global or mixture streaming velocity component, the
same as if the <I>velocity</I> keyword were not used.
</P>
<P>The formulas for the <I>vxvar</I>, <I>vyvar</I>, <I>vzvar</I> variables can use one
or two or three variables which will store the x, y, or z coordinates
of the particle that is being created.  If used, these other variables
must be <A HREF = "variable.html">internal-style variables</A> defined in the input
script; their initial numerica values can by anything.  Their names
are specified as <I>xvar</I>, <I>yvar</I>, and <I>zvar</I>.  If any of them is not
used in the <I>vxvar</I>, <I>vyvar</I>, <I>vzvar</I> formulas, it can be specified as
NULL.
</P>
<P>When a particle is added, its coordinates are stored in <I>xvar</I>,
<I>yvar</I>, <I>zvar</I> if they are defined.  The <I>vxvar</I>, <I>vyvar</I>, <I>vzvar</I>
variables are then evaluated.  The returned values are used to set the
streaming velocity of that particle.  A thermal velocity is also added
to the particle, using the the global or mixture temperature, as
described above.
</P>
<P>As an example, these commands can be used in a 2d simulation, to give
particles an initial velocity pointing towards the upper right corner
of the domain with a magnitude that makes them all reach that point at
the same time (assuming their thermal velocity is small and it is not
a collisional flow).  Click on the image to play an animation of the
effect.
</P>
<PRE>variable x internal 0
variable y internal 0
variable vx equal (xhi-v_x)/(1000*7.0e-9)  # timesteps and timestep-size
variable vy equal (yhi-v_y)/(1000*7.0e-9)
create_particles air n 10000 velocity vx vy NULL x y NULL 
</PRE>
<CENTER><A HREF = "JPG/velocity_variation.gif"><IMG SRC = "JPG/velocity_variation_small.jpg"></A>
</CENTER>
<P>The <I>twopass</I> keyword does not require a value.  If used, the
creation procedure will loop over the creation grid cells twice, the
same as the KOKKOS package version of this command does, so that it can
reallocate memory efficiently, e.g. on a GPU.  If this keyword is used
the non-KOKKOS and KOKKOS version will generate exactly the same set
of particles, which makes debugging easier.  If the keyword is not
used, the non-KOKKOS and KOKKOS runs will use random numbers
differently and thus generate different particles, though they will be
statistically similar.
</P>
<HR>

<P>This command (or more generically styles) can take a suffix as shown
at the top of this page.
</P>
<P>Styles with a <I>kk</I> suffix are functionally the same as the
corresponding style without the suffix.  They have been optimized to
run faster, depending on your available hardware, as discussed in the
<A HREF = "Section_accelerate.html">Accelerating SPARTA</A> section of the manual.
The accelerated styles take the same arguments and should produce the
same results, except for different random number, round-off and
precision issues.
</P>
<P>These accelerated styles are part of the KOKKOS package. They are only
enabled if SPARTA was built with that package.  See the <A HREF = "Section_start.html#start_3">Making
SPARTA</A> section for more info.
</P>
<P>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <A HREF = "Section_start.html#start_6">-suffix command-line
switch</A> when you invoke SPARTA, or you can
use the <A HREF = "suffix.html">suffix</A> command in your input script.
</P>
<P>See the <A HREF = "Section_accelerate.html">Accelerating SPARTA</A> section of the
manual for more instructions on how to use the accelerated styles
effectively.
</P>
<HR>

<P><B>Restrictions:</B> none
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "mixture.html">mixture</A>, <A HREF = "fix_emit_face.html">fix emit/face</A>
</P>
<P><B>Default:</B>
</P>
<P>The option default is global = no.
</P>
</HTML>
